home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / e / kyz_obj.lha / doc / bitfield.doc next >
Text File  |  1998-10-18  |  8KB  |  281 lines
  1. TABLE OF CONTENTS
  2.  
  3. bitfield.m/--overview--
  4. bitfield.m/bit_operations
  5. bitfield.m/bitfield_combine
  6. bitfield.m/bitfield_operations
  7. bitfield.m/end
  8. bitfield.m/field_operations
  9. bitfield.m/field_range
  10. bitfield.m/new
  11. bitfield.m/range_errors
  12. bitfield.m/--overview--                               bitfield.m/--overview--
  13.  
  14.    PURPOSE
  15.     To provide a multi-purpose bitfield.
  16.  
  17.    OVERVIEW
  18.     Bitfields  are a simple way of encoding a set of true/false states
  19.     for  a  number  of integer values. Rather than use a lookup table,
  20.     you can use a bitfield which holds 8 states per byte.
  21.  
  22.     Basically, the bitfield is a collection of individual 'bits', each
  23.     of which is a simple boolean value, TRUE or FALSE.
  24.     
  25.     You  can  set,  clear,  and test individual bit and ranges of bits
  26.     within  the bitfield. You can ask the bitfield either to ignore or
  27.     raise  exceptions  if you step outside of it. You can also combine
  28.     bitfields logically.
  29.  
  30. bitfield.m/bit_operations                           bitfield.m/bit_operations
  31.  
  32.    NAME
  33.     bitfield.set() -- set an individual bit.
  34.     bitfield.clear() -- clear an individual bit.
  35.     bitfield.toggle() -- toggle an individual bit.
  36.     bitfield.test() -- test an individual bit.
  37.  
  38.    SYNOPSIS
  39.     state := set(bit)
  40.     state := clear(bit)
  41.     state := toggle(bit)
  42.     state := test(bit)
  43.  
  44.    FUNCTION
  45.     Will  test,  then perform an operation on an individual bit in the
  46.     bitfield:
  47.  
  48.     set()    will set the bit to boolean TRUE.
  49.     clear()  will clear the bit to boolean FALSE.
  50.     toggle() will change a boolean FALSE bit to TRUE, and vice-versa.
  51.     test()   will perform no altering operation on the bit.
  52.  
  53.     If  the bit specified is outwith the range stored by the bitfield,
  54.     a range error will occur.
  55.  
  56.    INPUTS
  57.     bit   - the bit to perform an operation on.
  58.  
  59.    RESULT
  60.     state - the  previous  state  of  the bit before the operation was
  61.             performed on it, either TRUE or FALSE.
  62.  
  63.    SEE ALSO
  64.     bitfield_operations(), range_errors()
  65.  
  66. bitfield.m/bitfield_combine                       bitfield.m/bitfield_combine
  67.  
  68.    NAME
  69.     bitfield.copy() -- copy from another bitfield.
  70.     bitfield.and() -- mask bitfield with another.
  71.     bitfield.or() -- overlay from another bitfield.
  72.     bitfield.xor() -- perform exclusive-or combine of bitfield.
  73.  
  74.    SYNOPSIS
  75.     bitfield.copy(bitfield2)
  76.     bitfield.and(bitfield2)
  77.     bitfield.or(bitfield2)
  78.     bitfield.xor(bitfield2)
  79.  
  80.    FUNCTION
  81.     Will  perform  a  logical operation on the bitfield using the data
  82.     held in another bitfield.
  83.  
  84.     Currently,  both  bitfields  must be exactly the same size as each
  85.     other, or a range error will occur.
  86.  
  87.     b1.copy(b2) will perform  b1 := b2
  88.     b1.and(b2)  will perform  b1 := b1 AND b2
  89.     b1.or(b2)   will perform  b1 := b1 OR b2
  90.     b1.xor(b2)  will perform  b1 := b1 XOR b2
  91.  
  92.     If  the  bitfield  specified  falls  in  any way outwith the range
  93.     stored by the bitfield, a range error will occur.
  94.  
  95.    INPUTS
  96.     bitfield2 - pointer to another instance of the bitfield class.
  97.  
  98.    RESULT
  99.     Always returns TRUE, except if a range error occurs, in which case
  100.     it will return FALSE.
  101.  
  102.    SEE ALSO
  103.     range_errors()
  104.  
  105. bitfield.m/bitfield_operations                 bitfield.m/bitfield_operations
  106.  
  107.    NAME
  108.     bitfield.bf_set() -- set a range of bits.
  109.     bitfield.bf_clear() -- clear a range of bits.
  110.     bitfield.bf_invert() -- invert a range of bits.
  111.     bitfield.bf_test() -- test a range of bit.
  112.  
  113.    SYNOPSIS
  114.     andstate, orstate := bf_set(leftbit, rightbit)
  115.     andstate, orstate := bf_clear(leftbit, rightbit)
  116.     andstate, orstate := bf_invert(leftbit, rightbit)
  117.     andstate, orstate := bf_test(leftbit, rightbit)
  118.  
  119.    FUNCTION
  120.     Will  test all of, then perform an operation on a range of bits in
  121.     the bitfield:
  122.  
  123.     bf_set()    will set all affected bits to boolean TRUE.
  124.     bf_clear()  will clear all affected bits to boolean FALSE.
  125.     bf_invert() will change boolean FALSE bits to TRUE, and vice-versa.
  126.     bf_test()   will perform no altering operation on the bits.
  127.  
  128.     If  the  bitfield  specified  falls  in  any way outwith the range
  129.     stored by the bitfield, a range error will occur.
  130.  
  131.    INPUTS
  132.     leftbit, rightbit - the  bits you  want to affect, from leftbit to
  133.                         rightbit  (inclusive).  left and right will be
  134.                         swapped automatically if right < left.
  135.  
  136.    RESULT
  137.     andstate - an  AND-based  combination  of  the  states  of all the
  138.                affected bits before any changes were made.
  139.  
  140.                If ALL of the bits were TRUE, the andstate is TRUE
  141.                If any of the bits were FALSE, the andstate is FALSE.
  142.  
  143.     orstate  - an  OR-based  combination  of  the  states  of  all the
  144.                affected bits before any changes were made.
  145.  
  146.                If ANY of the bits were TRUE, the orstate is TRUE
  147.                If all of the bits were FALSE, the orstate is FALSE.
  148.  
  149.    SEE ALSO
  150.     bit_operations(), range_errors()
  151.  
  152. bitfield.m/end                                                 bitfield.m/end
  153.  
  154.    NAME
  155.     bitfield.end() -- Destructor.
  156.  
  157.    SYNOPSIS
  158.     end()
  159.  
  160.    FUNCTION
  161.     Frees resources used by an instance of the bitfield class.
  162.  
  163.    SEE ALSO
  164.     new()
  165.  
  166. bitfield.m/field_operations                       bitfield.m/field_operations
  167.  
  168.    NAME
  169.     bitfield.setfield() -- set all bits.
  170.     bitfield.clearfield() -- clear all bits.
  171.     bitfield.invert() -- invert all bits.
  172.  
  173.    SYNOPSIS
  174.     setfield()
  175.     clearfield()
  176.     invert()
  177.  
  178.    FUNCTION
  179.     setfield() sets all bits in the bitfield to boolean TRUE.
  180.     clearfield() clears all bits in the bitfield to boolean FALSE.
  181.     invert() switches all bits to their opposite boolean value.
  182.  
  183.     These  functions are more optimised than using the ranged bitfield
  184.     operations over the entire range.
  185.  
  186.    SEE ALSO
  187.     bitfield_operations()
  188.  
  189. bitfield.m/field_range                                 bitfield.m/field_range
  190.  
  191.    NAME
  192.     bitfield.range() -- report range of representable integers.
  193.  
  194.    SYNOPSIS
  195.     min, max := range()
  196.  
  197.    FUNCTION
  198.     Returns  the  minimum  and  maximum  represented  integers in this
  199.     instance, as defined in the construction.
  200.  
  201.    RESULT
  202.     min - the minimum representable integer in this bitfield.
  203.     max - the maximum representable integer in this bitfield.
  204.  
  205.    SEE ALSO
  206.     new()
  207.  
  208. bitfield.m/new                                                 bitfield.m/new
  209.  
  210.    NAME
  211.     bitfield.new() -- Constructor.
  212.  
  213.    SYNOPSIS
  214.     new(min, max)
  215.     new(min, max, range)
  216.  
  217.    FUNCTION
  218.     Initialises  an  instance  of the bitfield class. Raises exception
  219.     "MEM"  if it cannot allocate enough memory for the required number
  220.     of bits. All bits are initially cleared.
  221.  
  222.    INPUT
  223.     min   - the  minimum integer value that will be represented in the
  224.             field. This can be negative.
  225.  
  226.     max   - the  maximum integer value that will be represented in the
  227.             field.  This  can  also  be negative, and can also be less
  228.             than min (the values will be swapped if they are).
  229.  
  230.     range - whether range errors are fatal or not. See range_errors().
  231.             The default for this argument is FALSE.
  232.  
  233.    SEE ALSO
  234.     end(), range(), range_errors()
  235.  
  236. bitfield.m/range_errors                               bitfield.m/range_errors
  237.  
  238.    NAME
  239.     bitfield.range_errors() -- define range error handling.
  240.  
  241.    SYNOPSIS
  242.     oldstate := range_errors(newstate)
  243.  
  244.    FUNCTION
  245.     Defines  the  handling  of  range errors with this instance of the
  246.     bitfield.
  247.  
  248.     A  range  error  occurs  when  you  try  an  operation that cannot
  249.     logically  perform  its  function  with  the  parameters  you have
  250.     specified. For example, trying to toggle a bit that is outside the
  251.     range of the bitfield, or trying to combine two bitfields that are
  252.     not the same size.
  253.  
  254.     When  a range error occurs, what happens next depends on the state
  255.     of  the range_errors flag for the bitfield instance, as set in the
  256.     construction, or at runtime with this function.
  257.  
  258.     If  range_errors  =  FALSE,  NO  OPERATION  WILL  OCCUR,  and  the
  259.     operation will immediately return FALSE.
  260.  
  261.     If range_errors = TRUE, NO OPERATION WILL OCCUR, and the operation
  262.     will throw the exception "rnge".
  263.  
  264.     It is essential to realise that NO operation happens when there is
  265.     a  range  error. range_errors=FALSE does NOT mean that 'errors are
  266.     ignored'. It means that 'errors do not throw an exception'.
  267.  
  268.     An  analogy  is  that  range_errors=TRUE  makes  errors  'loud' or
  269.     'fatal'.
  270.  
  271.    INPUTS
  272.     newstate - a TRUE or FALSE value to set the range_er